| old name | new name | feature |
|:-----:|:-----:|:-----|
| method | oldMethod | script.js,Class,method |
| cachedMethod | method | script.js,Class,method including computed property names |
- [Hook Callback Compatibility] Since 0.0.149 with #123, the hook callback function has to support new operators for hooking in strict mode. See below for the updated hook callback function hook.__hook__. hook.hookCallbackCompatibilityTest() can detect if the target hook callback function is compatible or not.
- [Opaque URL Authorization] Since 0.0.178 with #178, all opaque content URLs must be authorized via hook.parameters.opaque = [ 'opaque_url', ..., (url) => url.match(/opaque_url_pattern/), ... ] configuration.

$3

Demo on GitHub Pages

$3

`javascript
const hook = require('thin-hook/hook.js');
let code = fs.readFileSync('src/target.js', 'UTF-8');
let initialContext = [['src/target.js', {}]];
let gen = hook(code, '__hook__', initialContext, 'hash');
fs.writeFileSync('hooked/target.js', gen);
fs.writeFileSync('hooked/target.js.contexts.json', JSON.stringify(contexts, null, 2));
`

$3

`javascript
// Built-in Context Generator Function
hook.contextGenerators.method = function generateMethodContext(astPath) {
return astPath.map(([ path, node ], index) => node && node.type
? (node.id && node.id.name ? node.id.name : (node.key && node.key.name
? (node.kind === 'get' || node.kind === 'set' ? node.kind + ' ' : node.static ? 'static ' : '') + node.key.name : ''))
: index === 0 ? path : '').filter(p => p).join(',');
}
`

`javascript
// Example Custom Context Generator Function with Hashing
const hashSalt = '__hash_salt__';
let contexts = {};

hook.contextGenerators.hash = function generateHashContext(astPath) {
const hash = hook.utils.createHash('sha256');
let hashedInitialContext = astPath[0][0];
astPath[0][0] = contexts[hashedInitialContext] || astPath[0][0];
let methodContext = hook.contextGenerators.method(astPath);
astPath[0][0] = hashedInitialContext;
hash.update(hashSalt + methodContext);
let hashContext = hash.digest('hex');
contexts[hashContext] = methodContext;
return hashContext;
}
`

`javascript
{
// Authorization Tickets for no-hook scripts
// Ticket for this script itself is specified in URL of script tag as
// hook.min.js?no-hook-authorization={ticket}
// Note: no-hook-authorization must not exist in learning mode
let noHookAuthorization = {
// '*' is for learning mode to detect authorization tickets in
// hook.parameters.noHookAuthorizationPassed,
// hook.parameters.noHookAuthorizationFailed
// JSONs are output to console in the learning mode
//'*': true,
"35ae97a3305b863af7eb0ac75c8679233a2a7550e4c3046507fc9ea182c03615": true,
"16afd3d5aa90cbd026eabcc4f09b1e4207a7042bc1e9be3b36d94415513683ed": true,
"ae11a06c0ddec9f5b75de82a40745d6d1f92aea1459e8680171c405a5497d1c8": true,
"5b7ebf7b0b2977d44f47ffa4b19907abbc443feb31c343a6cbbbb033c8deb01a": true,
"c714633723320be54f106de0c50933c0aeda8ac3fba7c41c97a815ed0e71594c": true,
"2f43d927664bdfcbcb2cc4e3743652c7eb070057efe7eaf43910426c6eae7e45": true,
"b397e7c81cca74075d2934070cbbe58f345d3c00ff0bc04dc30b5c67715a572f": true,
"02c107ea633ed697acc12e1b3de1bcf2f0ef7cafe4f048e29553c224656ecd7a": true,
"aebb23ce36eb6f7d597d37727b4e6ee5a57aafc564af2d65309a9597bfd86625": true
};
let hidden;
const passcode = 'XX02c107ea633ed697acc12e1b3de1bcf2f0ef7cafe4f048e29553c224656ecd7a';
if (typeof self === 'object' && self.constructor.name === 'ServiceWorkerGlobalScope') {
// Service Worker
let reconfigure = false;
if (hook.parameters.noHookAuthorization) {
if (Object.getOwnPropertyDescriptor(hook.parameters, 'noHookAuthorization').configurable) {
reconfigure = true;
}
}
else {
reconfigure = true;
}
if (reconfigure) {
Object.defineProperty(hook.parameters, 'noHookAuthorization', {
configurable: false,
enumerable: true,
get() {
return hidden;
},
set(value) {
if (value && value.passcode === passcode) {
delete value.passcode;
Object.freeze(value);
hidden = value;
}
}
});
}
noHookAuthorization.passcode = passcode;
hook.parameters.noHookAuthorization = noHookAuthorization;
}
else {
// Browser Document
Object.defineProperty(hook.parameters, 'noHookAuthorization', {
configurable: false,
enumerable: true,
writable: false,
value: Object.freeze(noHookAuthorization)
});
}
if (!noHookAuthorization['*']) {
Object.seal(hook.parameters.noHookAuthorizationPassed);
}
}
{
// source map target filters
hook.parameters.sourceMap = [
url => location.origin === url.origin && url.pathname.match(/^\/components\/thin-hook\/demo\//)
];
// hook worker script URL
hook.parameters.hookWorker = hook-worker.js?no-hook=true;
}
`

`javascript
// Hook worker script (demo/hook-worker.js)
//
// Configuration:
// hook.parameters.hookWorker = hook-worker.js?no-hook=true;
importScripts('../hook.min.js?no-hook=true', 'context-generator.js?no-hook=true', 'bootstrap.js?no-hook=true');
onmessage = hook.hookWorkerHandler;
`

`html




`

$3

`javascript
// Built-in Minimal Hook Callback Function without hooking properties (hook-property=false)
hook.__hook_except_properties__ = function __hook_except_properties__(f, thisArg, args, context, newTarget) {
return newTarget
? Reflect.construct(f, args)
: thisArg
? f.apply(thisArg, args)
: f(...args);
}
`

`javascript
// the global object
const _global = (new Function('return this'))();

// helper for strict mode
class StrictModeWrapper {
static '#.' { return o[p]; }
static ['#[]'](o, p) { return o[p]; }
static '#*' { return o; }
static '#in' { return p in o; }
static '#()' { return op; }
static '#p++' { return o[p]++; }
static '#++p' { return ++o[p]; }
static '#p--' { return o[p]--; }
static '#--p' { return --o[p]; }
static '#delete' { return delete o[p]; }
static '#=' { return o[p] = v; }
static '#+=' { return o[p] += v; }
static '#-=' { return o[p] -= v; }
static '#=' { return o[p] = v; }
static '#/=' { return o[p] /= v; }
static '#%=' { return o[p] %= v; }
static '#=' { return o[p] = v; }
static '#<<=' { return o[p] <<= v; }
static '#>>=' { return o[p] >>= v; }
static '#>>>=' { return o[p] >>>= v; }
static '#&=' { return o[p] &= v; }
static '#^=' { return o[p] ^= v; }
static '#|=' { return o[p] |= v; }
static '#.=' { return { set '=' { o[p] = v; }, get ['=']() { return o[p]; } }; }
}

// Built-in Minimal Hook Callback Function with hooking properties (hook-property=true) - default
function __hook__(f, thisArg, args, context, newTarget) {
let normalizedThisArg = thisArg;
if (newTarget === false) { // resolve the scope in 'with' statement body
let varName = args[0];
let __with__ = thisArg;
let scope = _global;
let _scope;
let i;
for (i = 0; i < __with__.length; i++) {
_scope = __with__[i];
if (Reflect.has(_scope, varName)) {
if (_scope[Symbol.unscopables] && _scope[Symbol.unscopables][varName]) {
continue;
}
else {
scope = _scope;
break;
}
}
}
thisArg = normalizedThisArg = scope;
}
let result;
let args1 = args[1]; // for '()'
function * gen() {}
let GeneratorFunction = gen.constructor;
switch (f) {
case Function:
args = hook.FunctionArguments('__hook__', [[context, {}]], 'method', args);
break;
case GeneratorFunction:
args = hook.FunctionArguments('__hook__', [[context, {}]], 'method', args, true);
break;
case '()':
case '#()':
switch (thisArg) {
case Reflect:
switch (args[0]) {
case 'construct':
if (args[1]) {
switch (args[1][0]) {
case Function:
args1 = [args[1][0], hook.FunctionArguments('__hook__', [[context, {}]], 'method', args[1][1])];
if (args[1][2]) {
args1.push(args[1][2]);
}
break;
default:
if (args[1][0].prototype instanceof Function) {
args1 = [args[1][0], hook.FunctionArguments('__hook__', [[context, {}]], 'method', args[1][1], args[1][0].prototype instanceof GeneratorFunction)];
if (args[1][2]) {
args1.push(args[1][2]);
}
}
break;
}
}
break;
case 'apply':
if (args[1]) {
switch (args[1][0]) {
case Function:
args1 = [args[1][0], args[1][1], hook.FunctionArguments('__hook__', [[context, {}]], 'method', args[1][2])];
break;
case GeneratorFunction:
args1 = [args[1][0], args[1][1], hook.FunctionArguments('__hook__', [[context, {}]], 'method', args[1][2], true)];
break;
default:
if (args[1][0].prototype instanceof Function) {
args1 = [args[1][0], args[1][1], hook.FunctionArguments('__hook__', [[context, {}]], 'method', args[1][2], args[1][0].prototype instanceof GeneratorFunction)];
}
break;
}
}
break;
default:
break;
}
break;
case Function:
switch (args[0]) {
case 'apply':
args1 = [args[1][0], hook.FunctionArguments('__hook__', [[context, {}]], 'method', args[1][1])];
break;
case 'call':
args1 = [args[1][0], ...hook.FunctionArguments('__hook__', [[context, {}]], 'method', args[1].slice(1))];
break;
default:
break;
}
break;
case GeneratorFunction:
switch (args[0]) {
case 'apply':
args1 = [args[1][0], hook.FunctionArguments('__hook__', [[context, {}]], 'method', args[1][1], true)];
break;
case 'call':
args1 = [args[1][0], ...hook.FunctionArguments('__hook__', [[context, {}]], 'method', args[1].slice(1), true)];
break;
default:
break;
}
break;
default:
if (thisArg instanceof GeneratorFunction && args[0] === 'constructor') {
args1 = hook.FunctionArguments('__hook__', [[context, {}]], 'method', args[1], true);
}
else if (thisArg instanceof Function && args[0] === 'constructor') {
args1 = hook.FunctionArguments('__hook__', [[context, {}]], 'method', args[1]);
}
break;
}
break;
default:
if (typeof f === 'function') {
if (f.prototype instanceof Function && newTarget) {
args = hook.FunctionArguments('__hook__', [[context, {}]], 'method', args, f.prototype instanceof GeneratorFunction);
}
else if (newTarget === '') {
if (args[0] && Object.getPrototypeOf(args[0]) === Function) {
args = [ args[0], ...hook.FunctionArguments('__hook__', [[context, {}]], 'method', args.slice(1)) ];
}
}
}
break;
}
if (typeof f !== 'string') {
result = newTarget
? Reflect.construct(f, args)
: thisArg
? f.apply(thisArg, args)
: f(...args);
}
else {
// property access
switch (f) {
// getter
case '.':
case '[]':
result = thisArg[args[0]];
break;
// enumeration
case '*':
result = thisArg;
break;
// property existence
case 'in':
result = args[0] in thisArg;
break;
// funcation call
case '()':
result = thisArg[args[0]](...args1);
break;
// unary operators
case 'p++':
result = thisArg[args[0]]++;
break;
case '++p':
result = ++thisArg[args[0]];
break;
case 'p--':
result = thisArg[args[0]]--;
break;
case '--p':
result = --thisArg[args[0]];
break;
case 'delete':
result = delete thisArg[args[0]];
break;
// assignment operators
case '=':
result = thisArg[args[0]] = args[1];
break;
case '+=':
result = thisArg[args[0]] += args[1];
break;
case '-=':
result = thisArg[args[0]] -= args[1];
break;
case '*=':
result = thisArg[args[0]] *= args[1];
break;
case '/=':
result = thisArg[args[0]] /= args[1];
break;
case '%=':
result = thisArg[args[0]] %= args[1];
break;
case '**=':
result = thisArg[args[0]] **= args[1];
break;
case '<<=':
result = thisArg[args[0]] <<= args[1];
break;
case '>>=':
result = thisArg[args[0]] >>= args[1];
break;
case '>>>=':
result = thisArg[args[0]] >>>= args[1];
break;
case '&=':
result = thisArg[args[0]] &= args[1];
break;
case '^=':
result = thisArg[args[0]] ^= args[1];
break;
case '|=':
result = thisArg[args[0]] |= args[1];
break;
// LHS property access
case '.=':
result = { set '=' { thisArg[args[0]] = v; }, get ['=']() { return thisArg[args[0]]; } };
break;
// strict mode operators prefixed with '#'
// getter
case '#.':
case '#[]':
result = StrictModeWrapper'#.';
break;
// enumeration
case '#*':
result = StrictModeWrapper'#*';
break;
// property existence
case '#in':
result = StrictModeWrapper'#in';
break;
// funcation call
case '#()':
result = StrictModeWrapper'#()';
break;
// unary operators
case '#p++':
result = StrictModeWrapper'#p++';
break;
case '#++p':
result = StrictModeWrapper'#++p';
break;
case '#p--':
result = StrictModeWrapper'#p--';
break;
case '#--p':
result = StrictModeWrapper'#--p';
break;
case '#delete':
result = StrictModeWrapper'#delete';
break;
// assignment operators
case '#=':
result = StrictModeWrapper'#=';
break;
case '#+=':
result = StrictModeWrapper'#+=';
break;
case '#-=':
result = StrictModeWrapper'#-=';
break;
case '#*=':
result = StrictModeWrapper'#*=';
break;
case '#/=':
result = StrictModeWrapper'#/=';
break;
case '#%=':
result = StrictModeWrapper'#%=';
break;
case '#**=':
result = StrictModeWrapper'#**=';
break;
case '#<<=':
result = StrictModeWrapper'#<<=';
break;
case '#>>=':
result = StrictModeWrapper'#>>=';
break;
case '#>>>=':
result = StrictModeWrapper'#>>>=';
break;
case '#&=':
result = StrictModeWrapper'#&=';
break;
case '#^=':
result = StrictModeWrapper'#^=';
break;
case '#|=':
result = StrictModeWrapper'#|=';
break;
// LHS property access
case '#.=':
result = StrictModeWrapper'#.=';
break;
// getter for super
case 's.':
case 's[]':
result = args1;
break;
// super method call
case 's()':
result = args2.apply(thisArg, args[1]);
break;
// unary operators for super
case 's++':
case '++s':
case 's--':
case '--s':
result = args[1].apply(thisArg, args);
break;
// assignment operators for super
case 's=':
case 's+=':
case 's-=':
case 's*=':
case 's/=':
case 's%=':
case 's**=':
case 's<<=':
case 's>>=':
case 's>>>=':
case 's&=':
case 's^=':
case 's|=':
result = args[2].apply(thisArg, args);
break;
// getter in 'with' statement body
case 'w.':
case 'w[]':
result = args[1]();
break;
// function call in 'with' statement body
case 'w()':
result = args2;
break;
// constructor call in 'with' statement body
case 'wnew':
result = args2;
break;
// unary operators in 'with' statement body
case 'w++':
case '++w':
case 'w--':
case '--w':
result = args[1]();
break;
// unary operators in 'with' statement body
case 'wtypeof':
case 'wdelete':
result = args[1]();
break;
// LHS value in 'with' statement body (__hook__('w.=', __with__, 'p', { set ['=' { p = v } } ], 'context', false)['='])
case 'w.=':
result = args[1];
break;
// assignment operators in 'with' statement body
case 'w=':
case 'w+=':
case 'w-=':
case 'w*=':
case 'w/=':
case 'w%=':
case 'w**=':
case 'w<<=':
case 'w>>=':
case 'w>>>=':
case 'w&=':
case 'w^=':
case 'w|=':
result = args2;
break;
// default (invalid operator)
default:
f(); // throw TypeError: f is not a function
result = null;
break;
}
}
return result;
}
`

`javascript
// Example Hook Callback Function with Primitive Access Control
hashContext = { 'hash': 'context', ... }; // Generated from hook.preprocess initialContext[0][1]
trustedContext = { 'context': /trustedModules/, ... }; // Access Policies

window.__hook__ = function __hook__(f, thisArg, args, context, newTarget) {
console.log('hook:', context, args);
if (!hashContext[context] ||
!trustedContext[hashContext[context]] ||
!(new Error('').stack.match(trustedContext[hashContext[context]]))) {
// plus check thisArg, args, etc.
throw new Error('Permission Denied');
}
return newTarget
? Reflect.construct(f, args)
: thisArg
? f.apply(thisArg, args)
: f(...args);
}
`

$3

If hooking is performed run-time in Service Worker, the entry HTML page must be loaded via Service Worker
so that no hook-targeted scripts are evaluated without hooking.

To achieve this, the static entry HTML has to be __Encoded__ at build time by hook.serviceWorkerTransformers.encodeHTML(html).

#### Hook CLI to encode the entry HTML

`sh
# encode src/index.html to dist/index.html
hook --out dist/index.html src/index.html
`

#### Decoded/Original HTML (source code)

`html







...

`

#### Encoded HTML (Service Worker converts it to Decoded HTML)

`html





`

- is inserted between the first hook.min.js script and the second no-hook script, which looks strange but is required for correct execution of no-hook scripts.
- If is inserted at the end of mandatory no-hook scripts according to the normal HTML format, the page encounters the unexpected "hook is not defined" error, whose root cause is under investigation.

Supported Syntax

- Functions
- Object Shorthand Methods ({ m() {} })
- ES6 Classes (constructor, super, this, new)
- ES6 Modules (import, export);
- Expressions in Template Literals( ${(v => v * v)(x)} )
- Generator Functions (function *g() { yield X })
- Arrow Functions (a => a, a => { return a; }, a => ({ p: a }))
- Async Functions (async function f() {}, async method() {}, async () => {})
- Default Parameters for Functions/Methods/Arrow Functions
- Default Parameters with Destructuring (function f([ a = 1 ], { b = 2, x: c = 3 }) {})
- Property Accessors (o.p, o['p'], o.p())

Install

$3

`sh
bower install --save thin-hook
`

$3

`sh
npm install --save thin-hook
`

Import

$3

`html


`

$3

`javascript
const hook = require('thin-hook/hook.js');
`

API (Tentative)

- hook(code: string, hookName: string = '__hook__', initialContext: Array = [], contextGeneratorName: string = 'method', metaHooking: boolean = true, hookProperty: boolean = true, sourceMap: object = null, asynchronous: boolean = false, compact: boolean = false, hookGlobal: boolean = true, hookPrefix: string = '_p_', initialScope: object = null)
- code: input JavaScript as string
- hookName: name of hook callback function
- initialContext: typically [ ['script.js', {}] ]
- contextGeneratorName: function property name in hook.contextGenerators
- argument astPath = [ ['script.js', {}], ['root', rootAst], ['body', bodyAst], ..., [0, FunctionExpressionAst] ]
- metaHooking: Enable meta hooking (run-time hooking of metaprogramming) if true
- hookProperty: Enable hooking of object property accessors and new operators if true
- sourceMap: Source map parameter in an object. { pathname: 'path/to/script_source.js'} Default: null
- asynchronous: Return a Promise if true. Default: false
- compact: Generate compact code if true. Default: false
- Note: sourceMap is disabled when compact is true
- hookGlobal: Hook global variable access. Must be enabled with hookProperty. Default: true
- hookPrefix: Prefix for hook.global()._p_GlobalVariable proxy accessors. Default: _p_
- Note: hook.global() return the global object with get/set accessors for the prefixed name
- initialScope: Initial scope object ({ vname: true, ... }) for hooked eval scripts. Default: null
- $hook$: $hook$ === hook. Alias of hook in hooked scripts
- hook.hookHtml(html: string, hookName, url, cors, contextGenerator, contextGeneratorScripts, isDecoded, metaHooking = true, scriptOffset = 0, _hookProperty = true, asynchronous = false)
- hook.__hook__(f: function or string, thisArg: object, args: Array, context: string, newTarget: new.target meta property)
- minimal hook callback function with property hooking
- f:
- function: target function to hook
- string: property operation to hook
- .: get property (o.prop)
- *: iterate over (for (p in o), for (p of o))
- in: property existence ('p' in o)
- (): function call (o.func())
- =, +=, ...: assignment operation (o.prop = value)
- p++, ++p, p--, --p: postfixed/prefixed increment/decrement operation (o.prop++)
- delete: delete operation (delete o.prop)
- s.: get property of super (super.prop)
- s(): call super method (super.method())
- s=, s+=, ...: assignment operation for super (super.prop = value)
- s++, ++s, s--, --s: postfixed/prefixed increment/decrement operation for super (super.prop++)
- w., w=, w(), w++, ...: operations on variables in within with statements
- thisArg: this object for the function or the operation
- args:
- arguments for the function
- [ property ] for property access operations
- [ property, value ] for property assignment operations
- [ property, [...args] ] for function call operations
- context: context in the script
- newTarget: new.target meta property for constructor calls;
- true for new calls
- Falsy values for non-new operations for faster detection of the operations
- false for with statement calls
- 0 for function calls
- undefined for other calls
- hook.__hook_except_properties__(f, thisArg, args, context, newTarget)
- minimal hook callback function without property hooking
- hook.hookCallbackCompatibilityTest(__hook__ = window[hookName], throwError = true, checkTypeError = true)
- run-time test suite for hook callback function
- Usage: window.__hook__ = function __hook__ (...) {}; hook.hookCallbackCompatibilityTest();
- An error is thrown on compatibility test failure.
- false is returned on a test failure if throwError = false
- tests on non-callable object's function call are skipped if checkTypeError = false
- hook.contextGenerators: object. Context Generator Functions
- null(): context as ''
- astPath(astPath: Array): context as 'script.js,[root]Program,body,astType,...'
- method(astPath: Array): context as 'script.js,Class,Method' with caching, including computed method variable name
- cachedMethod(astPath: Array): alias for method
- cachedMethodDebug(astPath: Array): context as 'script.js,Class,Method', comparing contexts with those by "oldMethod" in console.warn() messages
- oldMethod(astPath: Array): context as 'script.js,Class,Method' for compatibility
- custom context generator function has to be added to this object with its unique contextGeneratorName
- hook.$(symbolToContext = __hook__, contexts): context symbol generator function used in hooked scripts to generate symbols corresponding to given contexts
- Example call inserted at the beginning of a hooked script: const __context_mapper__ = $hook$.$(__hook__, [ 'examples/example2.js,C', ... ]);
- __context_mapper__: Array of symbol contexts
- In a hooked script, __context_mapper__ is actually __ + hex(sha256(topContextOfScript + code)) + __
- Note: Due to this specification, the same script in the same URL cannot be loaded to a single document multiple times
- __context_mapper__[N]: the symbol context corresponding to the string context contexts[N]
- __hook__[__context_mapper__[N]] is set as contexts[N] so that __hook__ can convert symbol contexts to their corresponding string contexts
- Hooked Native APIs: Automatically applied in hook() preprocessing
- hook.global(hookCallback: function = hookName, context: string, name: string, type: string)._p_name: hooked global variable accessor when hookGlobal is true
- type: one of 'var', 'function', 'let', 'const', 'class', 'get', 'set', 'delete', 'typeof'
- hook.Function(hookName, initialContext: Array = [['Function', {}]], contextGeneratorName): hooked Function constructor for use in hook callback function __hook__
- Usage: (new (hook.Function('__hook__', [['window,Function', {}]], 'method'))('return function f() {}'))()
- Notes:
- Avoid replacing the native API window.Function for better transparency (now commented out in the demo/hook-native-api.js)
- NOT automatically applied in the hooking
- Applied in the hook callback function (__hook__) instead
- hook.FunctionArguments(hookName, initialContext: Array = [['Function', {}]], contextGeneratorName = 'method', args, isGenerator = false): generate hooked Function arguments to hand to Function constructor for use in hook callback function __hook__
- Usage: hook.FunctionArguments('__hook__', [['window,Function', {}]], 'method', ['return function f() {}'])
- Returns hooked args in a cloned Array
- hook.eval(hookName, initialContext: Array = [['eval', {}]], contextGeneratorName): hooked eval function
- Usage: hook.eval('__hook__', [['eval', {}]], 'method'))('1 + 2', (script, eval) => eval(script))
- Note: In no-hook scripts with the hooked global eval function via hook.hook(hook.eval(...)), the evaluation is bound to the global scope unless the wrapper arrow function (script, eval) => eval(script) is defined in the local scope and specifed as the second argument of each eval() call
- hook.setTimeout(hookName, initialContext: Array = [['setTimeout', {}]], contextGeneratorName): hooked setTimeout function
- Note: Not automatically applied if the first argument is an (arrow) function expression
- hook.setInterval(hookName, initialContext: Array = [['setInterval', {}]], contextGeneratorName): hooked setInterval function
- Note: Not automatically applied if the first argument is an (arrow) function expression
- hook.Node(hookName, initialContext: Array = [['Node', {}]], contextGeneratorName): hook textContent property
- set textContent: hooked with context 'ClassName,set textContent'
- hook.Element(hookName, initialContext: Array = [['Element', {}]], contextGeneratorName): hook setAttribute function
- setAttribute('onXX', '{script in attribute}'): Script in onXX handler attribute is hooked
- setAttribute('href', 'javascript:{script in URL}'): Script in URL "javascript:{script in URL}" is hooked
- hook.HTMLScriptElement(hookName, initialContext: Array = [['HTMLScriptElement', {}]], contextGeneratorName): HTMLScriptElement with hooked properties
- Note: Applied only at run time. Not applied in preprocessing. HTMLScriptElement class is the same object as the native one. hook.Node and hook.Element are called internally.
- set textContent: Script in textContent is hooked if type is a JavaScript MIME type. Node.textContent is hooked as well.
- Note: Scripts set by innerHTML/outerHTML/text properties are NOT executed, while text should be executed according to the standards.
- set type: Script in this.textContent is hooked if type is a JavaScript MIME type.
- setAttribute('type', mimeType): Script in this.textContent is hooked if mimeType is a JavaScript MIME type. Element.setAttribute is hooked as well.
- hook.HTMLAnchorElement(hookName, initialContext: Array = [['HTMLAnchorElement', {}]]), contextGeneratorName): HTMLAnchorElement with hooked href property
- set href: Script in URL "javascript:{script in URL}" is hooked
- hook.HTMLAreaElement(hookName, initialContext: Array = [['HTMLAreaElement', {}]]), contextGeneratorName): HTMLAreaElement with hooked href property
- set href: Script in URL "javascript:{script in URL}" is hooked
- hook.Document(hookName, initialContext: Array = [['Document', {}]], contextGeneratorName): hook write function
- write('{script in string}'): Script in HTML fragment is hooked
- hook.with(scope: Object, ...scopes: Array of Object): Hook with statement scope object
- with (hook.with(obj, { v1: true, v2: true, ...})) {}
- hook.importScripts(): return hooked importScripts function for Workers, invalidating extensions other than .js and .mjs
- Note: No arguments to pass
- hook.hook(target: Class, ...): hook platform global object with target
- Usage: ['Function','setTimeout','setInterval',...].forEach(name => hook.hook(hook.Function('__hook__', [[name, {}]], 'method'))
- hook.serviceWorkerHandlers: Service Worker event handlers
- install: 'install' event handler. Set version from the version parameter
- activate: 'activate' event handler. Clear caches of old versions.
- message: 'message' event handler.
- INTERNAL 'channel' message: Transfer MessageChannel port objects for hook workers from the main document to the Service Worker at initialization
- INTERNAL 'unload' message: Trigger unloading of hook workers
- INTERNAL 'coverage' message: Transfer __coverage__ instanbul coverage object for the Service Worker to the main document to collect code coverage in test/hook.min.js
- ['plugin', 'pluginId', ...params ] message: Transfer a message to the target plugin identified by 'pluginId'. The target plugin must add its own event listener to handle the message.
- ['plugin', 'pluginId:enqueue', ...params ]: When the pluginId ends with :enqueue, events with posted messages are enqueued to hook.parameters.messageQueues['pluginId:enqueue'] = [] even before plugins are loaded into the Service Worker
- Each enqueued message is immediately responded via event.ports[0].postMessage() with a dummy response message generated by cloning the posted message and appending ':enqueued' such as ['plugin', 'pluginId:enqueue', ...params, ':enqueued' ]
- The target plugin must dequeue the enqueued events and append ':dequeued' to the queue to stop further enqueueing. For example, the queue [] changes as follows:
- An event is enqueued: [ event1 ]
- The plugin append ':dequeued': [ event1, ':dequeued' ]
- The plugin dequeues and processes the event(s): [ ':dequeued' ]
- Enqueued messages are likely to be one-way messages as the main document is about to reload itself
- hook.parameters.messageQueues['pluginId:enqueue'] may NOT exist when the plugin is loaded. So the plugin must create its own queue if it has not been created.
- fetch: 'fetch' event handler. Cache hooked JavaScripts and HTMLs except for the main page loading hook.min.js
- : arguments from the page
- version: default 1. Service Worker cache version. Old caches are flushed when the version is changed in the main page and reloaded. Service Worker is updated when the controlled page is detached after the reloading.
- sw-root: optional. Set Service Worker scope
- hook-name: default __hook__. hook callback function name
- context-generator-name: default method. context generator callback function name
- discard-hook-errors: true if errors in hooking are ignored and the original contents are provided. Default: true
- fallback-page: fallback page to land if Service Worker is not available in the browser
- no-hook-authorization: Optional. CSV of no-hook authorization tickets for no-hook scripts. Typically for ticket of no-hook authorization script itself.
- The values are stored in hook.parameters.noHookAuthorizationPreValidated object in Service Worker
- Add the value log-no-hook-authorization to log authorization in console
- Note: no-hook-authorization must not exist in learning mode with hook.parameters.noHookAuthorization['*'] === true
- Steps to update authorized no-hook scripts:
- 1. Let no-hook be "learning mode" by truthy hook.parameters.noHookAuthorization['*']
- 2. Remove (or temporarily rename) no-hook-authorization parameter from hook.min.js
- 3. Update no-hook script(s)
- 4. Clear Service Worker(s)
- 5. Update version parameter for hook.min.js
- 6. Check "Preserve Logs" option in debugger console
- 7. Reload the page(s) with no-hook script(s)
- 8. Copy and Paste values of hook.parameters.noHookAuthorizationPassed from both browser document and Service Worker to no-hook authorization script
- 9. Disable "learning mode"
- 10. Enable (or revive) no-hook-authorization parameter for hook.min.js with a dummy value
- 11. Clear Service Worker(s)
- 12. Update version parameter for hook.min.js
- 13. Reload the page(s) with no-hook scripts(s)
- 14. Copy and Paste the ticket for the no-hook authorization script into the no-hook-authorization parameter
- 15. Update version` parameter for hook.min.js
- 16. Clear Service Worker(s)
- 17. Reload the page(s) with no-hook script(s)
- 18. Check if there are no unauthorized no-hook scripts
-